Web API

An app can hook into the Web API (REST + Realtime), to allow for external access. A use case would for example be a Raspberry PI that reports it's status to Homey.

Your app's API edpoints are available under the following url: /api/app/com.yourapp.id/. All endpoints are by default protected, and the requesting user needs permission to your app (which is granted by default after installation). You can override this by setting public: true.

To add API endpoints to your app, create a file /api.js in your app's root folder. An example is shown below.

/api.js

module.exports = [

  {
    method: 'GET',
    path: '/',
    public: true,
    fn: function( args, callback ){
      const result = Homey.app.getSomething();

      // callback follows ( err, result )
      callback( null, result );

      // access /?foo=bar as args.query.foo
    }
  },

  {
    method: 'POST',
    path: '/',
    fn: function( args, callback ){
      const result = Homey.app.addSomething( args.body );
      if( result instanceof Error ) return callback( result );
      return callback( null, result );
    }
  },

  {
    method: 'PUT',
    path: '/:id',
    fn: function( args, callback ){
      const result = Homey.app.updateSomething( args.params.id, args.body );
      if( result instanceof Error ) return callback( result );
      return callback( null, result );
    }
  },

  {
    method: 'DELETE',
    path: '/:id',
    fn: function( args, callback ){
      const result = Homey.app.deleteSomething( args.params.id );
      if( result instanceof Error ) return callback( result );
      return callback( null, result );
    }
  }

]

Homey.app is the instance of your App.

Parameters

Possible parameters for an API endpoint object are:

The args object

The args object has three properties: body, query and params.

Body

This is an object with the body, when your request has method POST or PUT. JSON is automatically parsed.

Params

The params object is a set of strings defined in your path.

Query

The params object is a set of strings that are provided as query parameters, e.g. ?foo=bar will result in { "foo": "bar" }.

Realtime

Your app can emit 'realtime' events, which are one-way events to a subscribing client, e.g. a browser showing a Settings page.

/app.js

Homey.ManagerApi.realtime('my_event', 'my_json_stringifyable_value')
  .catch( this.error )